HI
Yes it's a good question. I have the same confuse when I first read that document.
Let me explain it to you.
First there are two ways to create Azure VM in Azure portal. Qurick create, and From gallary.
Both of these ways of create Azure VM does indeed end up in a cloud service container(If you know to Azure cloud service you should know that.) You can use Azure portal quick create a VM, then click "all items", you will find there are a cloud
service created for the specific VM with the same Name.
In your quick create when it asks for the DNS name (and shows the .cloudapp.net next to it) that's the Cloud Service name you are providing. (Senario 1)
When you do the create via the Gallery it is even more obvious on step 3 where is asks to create a new Cloud Service or select one that already exists.(Senario 2)
To do what you want via the REST API, you need Add role and
Create Virtual Machine Deployment
Add role url request
https://management.core.windows.net/<subscription-id>/services/hostedservices/<cloudservice-name>/deployments/<deployment-name>/roles
Create Virtual Machine Deployment
https://management.core.windows.net/<subscription-id>/services/hostedservices/<cloudservice-name>/deployments
See the difference?
Create Virtual Machine Deployment don't require your Deployments Name because the deployments name=cloudservice name. That's quick create VM (Senario 1) behavior.
Add role url request
Need your deployment Name, that's (Senario 2) behavior.